FishMarket 1.0

home *** CD-ROM | disk | FTP | other *** search

/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 476-500 / disk_484 / ezasm / ezasm.doc < prev next >

Wrap

Text File | 1992-05-06 | 23KB | 1,035 lines

EZAsm Version 1.5 March '91 by Joe Siebenmann DISCLAIMER: The following only applies to EZAsm, ez.lib, funcnm, funcdat, and related .doc files. ( A68k & Blink have their own distribution policies ) You have the right to freely use, copy and distribute this program as long as the following conditions are met: 1. The documentation is included with the program, and neither is modified in any way. 2. The program is not included in any package for profit unless written consent from the author is obtained. NOTE: The author does not accept any responsibility for any damage that might result from the use of this program. EZAsm was written to make programming in 68000 assembly language much easier! EZAsm combines parts of "C" with 68000 assembly, giving it the "feel" of a higher level language. The resulting code is optimized as much as possible. A68k ( by Charlie Gibbs ) and Blink ( from The Software Distillery ) are now included, and the offsets for all the 1.3 functions are now internal, so you'll have everything you need to start producing executables. Here are some of its advantages: o Your code is converted into the fastest possible assembly statement(s), so you automatically write "good" code. o More structured. Compare and bit test statements can have braces and "else" like "C". Being able to use braces lets you use assembly in a whole new way! o "C" like Amiga function calls! Every 1.3 function in every library is supported. An XREF table is automatically built and inserted if needed. o Makes code much more readable. You can code nearly twice as fast, with fewer syntax errors. o No more having to constantly look up which condition code to use for compares, bit tests, or maximum numbers for "moveq" or "addq" etc. o You can insert normal assembly statements anywhere, for your special needs. You need to know a little about assembly language and "C" operators before you dive right in. If you're new to 68000 assembly language, I suggest looking at one of the many available books on the subject. The included example source programs can give you a good idea about: o General statement syntax. o Use of "l", "w", "b" size arguments. o Using assembly statements in your code. **************************************** Using EZAsm: 1. Create a directory, and copy these files into it: ezasm, A68k, Blink, make1, ez.lib, funcnm, funcdat 2. Cd into your new directory, and you're ready to go! ( Another good method is to create an ALIAS to load these files into VD0: and work from there ) Make1 Make1 is a "make" like program, written in EZAsm, that will Execute() the necessary programs for you, creating an executable file with a minimum of effort. The source code is included. make1 [file] ( No extension. [file] is the filename with path if needed ) Execute()'s these commands: ezasm [file].s a68k [file].asm blink FROM [file].o LIBRARY ez.lib TO [file] EZAsm [path]file.s Where file is the name of your source file including any path. Give your source file an extension ( .s etc. ) or your linker will overwrite it. It produces an output file called file.asm. If you use other assemblers or linkers on the final output file, you may need to change the extension from .asm to .a etc.. A68k supports Manx's "CSEG" & "DSEG" which I like to use. You may need to change these to "SECTION name,CODE" etc. if using other assemblers. The code section has been made as compatible as possible. If your assembler complains, it's usually something in your data section. Manx: ezasm scroll.s ( c.lib supplies offsets ) as scroll.asm ln scroll.o -lc ********************************* * Operand Table * ********************************* Operand Type Mode [A] [B] [C] [D] [E] [F] Dn * * * - * - An * - * - - - (An) * * * * * * (An)+ * * * * * * -(An) * * * * * * d(An) * * * * * * d(An,Xn) * * * * * * abs.w * * * * * * abs.l * * * * * * d(PC) * - - - * * d(PC,Xn) * - - - * * immediate * - - - * - declared variables: "foo" becomes "foo(a5)" ( d(An) ) ************************************** ( decimal or hex ) #<1> 1 - 8 #<2> 0 - 7 #<3> 0 - 31 #<4> -128 - 127 #<any> any byte, word, or long size number Dn d0 - d7 An a0 - a7 {B} byte data size not allowed for An operands ******************************************** * legal * converted * legal * * operands * to * sizes * ******************************************** Addition Subtraction ++ -- [C] <op> addq/subq L,W,{B} += -= Dn <op> [A] add/sub L,W,B [D] <op> Dn add/sub L,W,B An <op> [A] adda/suba L,W [B] <op> #<any> addi/subi L,W,B [C] <op> #<1> addq/subq L,W,{B} Examples: Total ++ d1 += 10 Optional Args: l, w, b ********************************** Multiplication Division *= Dn *= [E] mulu W Dn *= ## * W /= Dn /= [E] divu W Examples: d0 *= d1 d2 /= 2 Optional Args: w, s ( signed divs/muls ) * This optimization results in code that's larger then "mulu" or "muls", but will execute much faster. Not all numbers can be optimized. If the number doesn't work, "mulu" or "muls" will be used, and the size will default to WORD. You can use a LONG, but if "mulu", or "muls" is used, it'll be truncated to a WORD. ( where ## is a word or byte length number ) ********************************** And Or Exclusive Or &= |= [B] <op> #<any> andi/ori L,W,B Dn <op> [E] and/or L,W,B [D] <op> Dn and/or L,W,B x= [B] x= Dn eor L,W,B [B] x= #<any> eori L,W,B Examples: Mask &= %11010000 Flags |= $f0 Optional Args: l, w, b *********************************** Shift Left/Right << >> Dn <op> Dn lsl/lsr L,W,B Dn <op> 1-31 * lsl/lsr L Dn <op> 1-8 lsl/lsr L,W,B [D] <op> 1 lsl/lsr W Examples: d2 << d0 d1 >> 4 Optional Args: l, w, b, a ( arithmetic shift asl/asr ) * Normally you're limited to shifting 1-8, or using a data register to hold higher. This optimized version is faster, and saves using a data register! ( logical shift only ) *********************************** Assign = [B] = [A] move L,W,{B} An = [A] movea L,W Dn = #<4> moveq L Examples: temp = Total (a1)+ = 0 w Optional Args: l, w, b *********************************** Compare >= <= != > < = Dn <op> [A] cmp L,W,{B} An <op> [A] cmpa L,W [B] <op> #<any> cmpi L,W,B (An)+ <op> (An)+ cmpm L,W,B Syntax types: [opr] <op> [opr] label [opr] <op> [opr] { . . } [opr] <op> [opr] { . . } else { . . } Examples: Total >= 100 Over Buf != 0 { FreeMem( Buf 100 ) } Optional Args: ( placed AFTER label or brace ) l, w, b, s ( signed ) ******************************************** Bit test Dn:0-31 = 0-1 label btst.l L Dn:Dn = 0-1 label L [F]:0-7 = 0-1 label btst.b B [F]:Dn = 0-1 label B ( You can also use braces instead of a label, see compare for use of braces ) Examples: d1:0 = 1 CalcRtn ($bfe001):6 = 0 LMBDown d2:d0 = 1 { rts } Optional Args: ( ignored ) Rules: o No spaces inside first operand. o Only "=" is allowed. o Right operand can only be 0 or 1. **************************************** Additional Arguments: b forces operation to be byte w " " " word l " " " long a arithmetic shift ( <<, >> ) s signed ( *=, /=, compares ) ( these are RESERVED and can't be used as variables, or labels ( unless you use upper case ) ) ****************************************************** Functions: Syntax examples: CloseWindow( Window ) Buf = AllocMem( 512 $10001 ) Permit( ) Example: -------------------------------- CLEAR_PUBLIC equ $10001 OLD equ 1005 LONG _DosBase FHandle num Rbuf _DosBase = OpenLibrary( "dos.library" 0 ) beq Exit Rbuf = AllocMem( 100 #CLEAR_PUBLIC ) beq Exit FHandle = Open( "df0:myfile" #OLD ) beq Exit d3 = 100 ; preload D3 *1 num = Read( d0 Rbuf * ) . . . *1 normally you wouldn't need to do this, it's only an example.. --------------------------------- o You must first do an OpenLibrary( ) to access functions in a library. Functions in ConsoleDevice are accessed differently, see the ConsoleDevice section in the RKM p 662. ( load the io_Device field into "_ConBase" ) Functions in ExecBase are always accessible and don't need to be opened. The library bases MUST be named: _ConBase _DiskfontBase _DosBase _ExpansionBase _GfxBase _IconBase _IntuitionBase _LayersBase _MathBase _MathIeeeDoubBasBase _MathIeeeDoubTransBase _MathTransBase _PotgoBase _RomBootBase _TimerBase _TranslatorBase o Unfortunately the leading underscores are necessary so you can use includes without your assembler complaining. Some library bases ( IntuitionBase, ExecBase, GfxBase, ExpansionBase, RomBootBase ) are already defined in some .i's resulting in "multiply defined symbol" errors. o You might notice that ExecBase is missing. It isn't needed. ( it's loaded with "movea.l $4,a6" ) Permit( ) OpenLibrary( "dos.library" 0 ) ^ ^ ^ no space | | space | space o The function name must be followed immediately with "(" ( no spaces between ) and then followed by a space or tab. If the function has no arguments, it still needs a space in the middle. Arguments must be separated with a space or tab. ReturnVar = AllocMem( FSize $10001 ) o All variables used in function calls, return variables or function arguments, should be LONG. a2 = ViewAddress( ) d1 = Read( "myfile" Buf BufLen ) o Address or data registers can also be used for returns if they're more convenient. Arguments: o If your argument is already in a DIFFERENT data or address register, you can pass it as an argument directly. Often a previous function will put results in D0, so just pass d0. If the proper register is already loaded, just pass "*". ( if you pass it the same register it uses, it'll be skipped. func defined as: D0 Lock( D1 D2 ) "Flock = Lock( d1 -2 )" arg "d1" will be skipped ) o EZAsm now supports argument strings surrounded by double quotes. The following "C" character constants are supported: \b backspace \f form feed \n newline \r carriage return \t horizontal tab \v vertical tab examples: "Hello, World!\n" "\t\tHeading\n" Strings are automatically null terminated. o To load a pointer to a newwindow or other "structure" you've defined use: #newwindow ( etc. ) it'll load its address into a data or address register. o if you need a pointer to one of your declared variables ( where the argument goes to an address register ) use: &foo ( address of "foo" ) ( output as "lea foo(a5),An" ) ( "&" is ONLY recognized inside function arguments ) o Sometimes you have to "play around" with using "#", "&", variables, constants etc. You might be giving it the contents of a variable, when it needs its address ( etc. ) All functions within these ( 1.3 ) libraries are supported: ConsoleDevice DiskfontBase DOSBase ExecBase ( SysBase ) ExpansionBase GfxBase IconBase IntuitionBase LayersBase MathBase MathIeeeDoubBasBase MathIeeeDoubTransBase MathTransBase PotgoBase RomBootBase TimerBase TranslatorBase o It keeps track of the current library base. As long as no user labels, or close braces ("}") are hit, it will skip reloading the base register for functions which use the same library base. o The file "funcnm" contains a list of every function that is supported. ************************************************** Optimizations: Aside from the many "normal" optimizations performed on statements, the following are also performed: STATEMENT BECOMES NOTE An = 0 sub.l An,An [B] = 0 clr [B] 1 ( compares ) [B] = 0 [B] != 0 tst [B] bxx label ---------------------------------- [B] += # [B] -= # [B] &= # [B] |= # [B] x= # [B] = # moveq #,d7 2 [opr].l d7,[B] ( compares ) Dn <op> # moveq #,d7 2 cmp.l d7,dn bxx label An <op> # moveq #,d7 2 cmpa.l d7,an bxx label ---------------------------------- Dn << 1-31 Dn >> 1-31 3, 2 An += #1 lea n(An),An An -= #1 lea -n(An),An 4, 2 An = #2 lea n,An 5, 2 Dn *= #1 6 # = 1-127 ( #<4> if appropriate ) #1 = any byte or word length number #2 = any byte, word, or long length number Notes: 1 For byte and word sizes the code size is smaller, for long, its smaller and faster. ( then "move #0,[B]" ) 2 Only apply to long sized operations. 3 The resulting instructions are combinations of "swap", "clr.w", "add.l", "lsr" or "lsl". 4 ( 1-8 handled by "addq", "subq" ) 5 ( 0 handled by "sub.l An,An" ) 6 The resulting instructions are combinations of "move.l", "asl.l", "asr.l", "add.l". ******************************************** General Info: o Statements can be indented as you like. Operands, operator, and arguments must be separated by at least one space or tab. o Braces can be nested up to 30 deep. o Only one statement per line. o If you declare variables or use function call's, the first statement in your code must be an "EZAsm statement" so it knows when to insert the XREF's and/or get stack frame for the variables. Comments, assembly directives, or assembly statements placed between your variables and the start of your code will be OUT OF PLACE in the output file. o Comments must begin with "*" or ";" and begin at column 1, or after statements ( separated from last argument or operand ) using ";". ( both types are transferred to output file ( some may not )) o Operands supported: @141 (octal), $61 (hex), %1100001 (binary), 'a' (ASCII), 97 (decimal). ASCII strings in operands can contain a maximum of 4 characters. ( no quotes within quotes permitted ) o To make labels and symbols as compatible as possible, they arn't checked for illegal characters. Typically the 1st character must be a letter, underscore "_", or a period "." . The rest of the characters can be any of these plus 0-9. o Labels and symbols are limited to a length of 127. ( Check your assembler to find what length they're significant to ( usually around 30)) o Labels that don't begin at column 1 should be followed immediately with ":". o Temporary labels of the form n$, where n consists of decimal digit(s), are supported. These labels are only in effect till the next non-temporary label is encountered. ( be careful of "hidden" labels generated by braces ) o No need to put in the usual "moveq #0,d0", "rts" at the end of your code, its part of the closing block of code it inserts. o D7 is used as a scratch register for some optimizations, so be careful if you use it. o Labels that it generates for braces are in the range ".laaa" to ".lzzz" so try to avoid using them. ( upper case is OK ) o Constants generated from argument strings are in the range: .c0 to .c0+n . Matching strings are not duplicated. o "SP", "PC", "CCR", "SR" & "USP" are supported, but you must ensure the size is legal as no checks are made. ( must be upper case ) o For best viewing of output file set your tabs to 8 spaces. ( printing should be fine ) IMPORTANT! : Use of register A5 is RESERVED! ( it contains the base address for variable storage ) ******************************** Variable Declaration: LONG foo Save[10] bar WORD DMASave BYTE Sw o "xxx[n]" reserves n consecutive blocks of given size, with "xxx" pointing to left-most byte. In the future this may be used for arrays. o You're limited to 14 variables per line. o No other statement types may occur between these lines. o Variables must be separated by at least one space, or tab. o To keep things word aligned, if an odd number of bytes are declared in BYTE, an extra byte will be added. This will offset the next "equ" by one. ( in the case of "BYTE Count foo buf[3]" ( 5 bytes ) an extra would be added ) o Must occur JUST BEFORE your program code. o Must begin at 1st column, with LONG, WORD, or BYTE in upper case. o EZAsm uses "link" to allocate space for variables on the stack. The maximum size of this space is 32K. If you need large blocks of memory use AllocMem( ). Since this stack space contains "garbage" code is added to clear it out before use. ( A0 and D0 are not disturbed ) What the stack frame looks like: LONG foo WORD bar Total LONG Cnt becomes... foo equ -4 bar equ -6 Total equ -8 Cnt equ -12 h l A5 base register i o | OOOO OO OO OOOOO memory bytes (-) 1119 87 65 4321 210 ( Sometimes variables are "adjusted" for proper loading, and "-2(a5)" or other displacement may appear in the output file instead of "foo(a5)" or other variable you might be expecting. ) ************************************************ How to get what you need, hints, etc.: END A68k only allows 2 "sections" of code. ( 1 CODE & 1 DATA ) This means you can only have 1 DATA section, on top or below. The DATA section is used here at the bottom, so all your data ( "dc.b", "ds.l" etc. ) should be placed BELOW the END statement. Any string constants which are generated will also appear below the END. In the final output file "END" will be adjusted, and everything will work out. ( EQU, XREF, XDEF etc. can go above your code with no problem ) o Instruction size: In most cases you won't need a size argument. It knows the size of the variables, address and data registers, and is smart enough to know what size to use. It determines the size of data by it's actual value not its physical size. ( $0020 %11010000 $12 125 are all BYTE size ) If the data is smaller than the instruction size you want, ( d1 = $20 w ) or it can't know an operands size ( (a2)+ = 3(a0) l ) you'll need to give it a size argument. Caution: Be aware that if you load small variables into larger ones, the upper bytes arn't cleared and may garbage your result. Always initialize your variables or restrict the size of the operation to "b" or "w". o Since "(a1)" refers to the CONTENTS of the byte, word, or long that A1 points to, "($dff180)" is used in a similar way. "move.w $dff01e,d0" would become, "d0 = ($dff01e) w". ( decimal addr's are also valid: "(123)" ) o When numbers are used as operands "$fe02" or "37", they are converted to "#$fe02" and "#37". When "$2f(a2)" or "15(a0)" type operands are used, they are left as is. ( see below ) o Operands that it doesn't recognize ( doesn't match with any declared LONG, WORD, BYTE, or standard "(a1)+" etc. ) get output as is. This is very useful when you need operands like: "#intuiname", "wd_UserPort(a1)", "$20(a1)", "DMACON(a6)" o Most instructions set condition code flags on the result of the operation. Often, instead of using a compare to check the result, you can use a branch on condition instruction "beq", "bne" etc. to jump to a location on the state of a condition code flag. You need to check which flags are set ( if any ) for an instruction. o If at any time you're unsure of what a statement is being output as, or want to check something out, just look at the output file. Well placed blank lines in your source code can enhance its readability. o I think it's a good idea to get away from using include files. It speeds up the assembler tremendously. Most assembly source files I see do this. **************************************** Errors: "Illegal argument" The argument found was not valid for the operator. See the list of "Optional Args" for the operator. It must be lower case, and be separated from the operands by at least a space or a tab. "Illegal operand" One, or both, of the operands are: not valid for the operator, have an invalid number, or byte size was specified for an "An" operand ( {B} ). In most cases it's looking for "Dn" or "An" as one of the operands. ( look under the "legal operands" of the operator for a valid combination ) "Illegal size" The argument size you specified is not valid for the operator. Check the "legal sizes" for the operator. "Needs size argument" It doesn't have enough size information about the operands to calculate an instruction size. You need to add an l, w, or b argument. "Label not found" No label matching your label argument was found. "Brace mismatch" Checks are made when a closing brace ( "}" ) is hit, and when "END" is hit. If the brace stack is "messed up" at that time, an error is given. If "}" is shown, look from there up. Both "}" and "END" may appear. If just "END", look for a "{" or "} else {" without a matching "}". "Function not found" No function matching your function name was found. Check case and spelling of function name, and be sure there isn't a space before the "(". Check the list of supported function names in the file "funcnm". "Function argument count incorrect" Check the number of arguments you used for the function. Too many or not enough were used. With string arguments, check for a missing '"'. Also look for a missing end ")". ( EZAsm doesn't do much checking of normal assembly statements. A68k and Blink will catch any problems missed by EZAsm and bring them to your attention ) ******************************************************************* ******************************************************************* If you try it, I think you'll like it. 8^) I'm always trying to improve EZAsm, and I'd really like to hear any ideas you have on making it better, even your complaints. So if you've found an "undocumented feature", or there's something you'd like to see in a future version please let me know. Enjoy! You can reach me at: Joe Siebenmann 8303 Old Tree Court Springfield, VA 22153 (703) 455-4982 or PLINK: IGZ798 ( please leave any messages in my mailbox )